Swift

You can integrate the Ditto SDK into Swift projects to develop native apps for Apple iOS and macOS platforms.

To install the Ditto SDK and start syncing offline:

1. Confirm that you meet the minimum requirements. (Prerequisites)

2. Install the necessary dependencies. (Installing Package Dependencies)

3. Set up your app permissions. (Configuring Permissions)

4. [Authenticate with the Big Peer and then start syncing offline. (Integrating and Initializing Sync)

Prerequisites

Following are the minimum requirements that must be met before attempting to install Ditto:

• iOS version 14 or later
• Mac Catalyst 14 or later
• macOS (AppKit) version 11 or later
• tvOS version 14 or later
• (optional) visionOS version 1, 1.1, or 1.2

Installing Package Dependencies

Using Xcode or CocoaPods, add the necessary dependencies:

Xcode

1. Click File, and then select Add Package Dependencies… from the menu.

2. In the modal that appears:

   1. Copy-paste the following URL into the search box in the upper-right corner: https://github.com/getditto/DittoSwiftPackage
   2. Select dittoswiftpackage from the list.
   3. Click Dependency Rule and select the version of Ditto you want to use:

   • If building a production-level app, see Developing for Production.
   • If testing Ditto with Apple Vision Pro devices, see Exploring with visionOS beta.

   4. Click Add Package.

   

   For more information, see the official Apple documentation > Adding package dependencies to your app.

3. From the Choose Package Products for DittoSwiftPackage modal:

   1. Click Add to Target and select your app from the list.
   2. Click Add Package.

   

Developing for Production

To install the latest production release of the Ditto SDK for Swift:

1. Click the Dependency Rule dropdown menu and select Up to Next Major Version from the list.

2. In the field on the right, set the version to 4.7.2.

   

Exploring with visionOS beta

Ditto now supports the visionOS platform in beta for our Swift SDK.

For an overview of the Ditto SDK for visionOS, including steps outlining example integration with our demo chat app, DittoChat, see visionOS on Swift.

To install the visionOS beta Ditto Swift package, set the Dependency Rule to 4.8.0-v as follows:

1. Click the Dependency Rule dropdown menu and select Exact Version from the list.

2. In the field on the right, set the version to 4.7.2.

   

For the visionOS binaries in GitHub, see 4.8.0-visionos-beta.1 library in the DittoSwiftPackage repo.

Configuring Permissions

Once you’ve added Ditto SDK package dependencies:

1. Configure your project’s Info.plist file to ensure the necessary permissions for Bluetooth Low Energy (LE) and local network services are included. (Ensuring Privacy Compliance)

2. If enabling the Data Protection entitlement, allow access after your end users have unlocked their device for the first time after a system restart. (Setting Protection Entitlement)

Ensuring Privacy Compliance

Configure your app for compliance with Apple’s guidelines for iOS permissions by doing the following. For more information, see the official Apple documentation for Privacy.

1. From Xcode, add a new Custom iOS Target Properties entry:

   1. From the left navigator area, click your project.
   2. In the editor that appears, click Info tab.
   3. Right-click any row in the list, and then select Add Row from the menu.

   For instructions on configuring permissions for your app, see Cloud Authentication.

   
2. From your project’s Info.plistfile, add the following key-value pairs, which display as dismissable prompts to your end users explaining why the app requires certain permissions.

   From Info Tab

   Key: NSBluetoothAlwaysUsageDescription
   Type: String
   Value: Uses Bluetooth to connect and sync with nearby devices
   Key: NSBluetoothPeripheralUsageDescription
   Type: String
   Value: Uses Bluetooth to connect and sync with nearby devices
   Key: NSLocalNetworkUsageDescription
   Type: String
   Value: Uses WiFi to connect and sync with nearby devices
   Key: NSBonjourServices
   Type: Array
   Value: Item0: "_http-alt._tcp." (String)
   

3. If your end users prefer a language other than English, replace each default string assigned to Value with their language equivalents.

4. From Xcode, ensure your app continues to sync while it runs in the background, as well as when the end-user device is locked by enabling Bluetooth Background Modes:

   1. From the left navigator area, click your project.
   2. Click Signing & Capabilities.
   3. Click + Capability and then, from the modal that appears, search and select Background Modes.
   4. From TARGETS, select your app from the list.
   5. From Background Modes, click to select the following:

   • Uses Bluetooth LE accessories
   • Acts as a Bluetooth LE accessory

   

Setting Protection Entitlement

If enabling the Data Protection entitlement, allow access after the end user has unlocked their device for the first time after a system restart by setting the entitlement to NSFileProtectionCompleteUntilFirstUserAuthentication.

For more information, see the official Apple documentation for Data Protection Entitlement.

Integrating and Initializing Sync

Once you’ve set up your environment, import the Ditto SDK in your codebase and obtain your access credentials.

Unless you have a specialized use case, such as a government app, you must connect to the internet at least once before you can sync offline with other peers.

1. From the top-most scope of your app’s codebase, add the following to set up authentication and start syncing offline.

2. Replace YOUR_APP_ID and YOUR_PLAYGROUND_TOKEN with your access credentials available from the portal.

   For instructions on how to obtain your access credentials, see Getting SDK Connection Details

   Swift

   ditto = Ditto(
     identity: DittoIdentity.onlinePlayground(
       appID: "REPLACE_ME_WITH_YOUR_APP_ID",
       token: "REPLACE_ME_WITH_YOUR_PLAYGROUND_TOKEN",
       enableDittoCloudSync: false, // This is required to be set to false to use the correct URLs
       customAuthURL: URL(string: "REPLACE_ME_WITH_YOUR_AUTH_URL")
     )
   )
   
   ditto.updateTransportConfig { transportConfig in
     // Set the Ditto Websocket URL
     transportConfig.connect.webSocketURLs.insert("wss://REPLACE_ME_WITH_YOUR_WEBSOCKET_URL")
     
     // P2P sync is enabled by default across all transports. Disable those
     // if you are only using Ditto Cloud Sync.
     transportConfig.setPeerToPeer(enabled: false)  
   }
   
   // Disable DQL strict mode so that collection definitions are not required in DQL queries
   try await ditto.store.execute("ALTER SYSTEM SET DQL_STRICT_MODE = false")
   
   do {
     try ditto.startSync()
   } catch {
     print(error.localizedDescription)
   }